feat: set up optimize docs instance and move one doc over #1166

pepopowitz · 2022-08-16T16:18:09Z

Part of #1116.

Adds a second docs plugin for Optimize documentation
Moves what-is-optimize doc into Optimize docs plugin
Configures sidebars for cross-plugin navigation
Updates links in documentation for cross-plugin navigation (what-is-optimize doc only)
Updates mappings in expandVersionedUrl based on the fact that there are no optimize versions yet
Adds a script and some instructions for generating the optimize_sidebars.js file

Scope

Only one doc is moved in this PR! But, it is completely moved, and the PR includes all setup needed so that we can iteratively move docs in ensuing PRs. It also demonstrates what all needs to be done to move a doc, so we should be able to follow it as a guide.

Out of scope of this PR

There are several details that are not included in this PR which disrupt the experience of reading/navigating docs within the Optimize section:

The "Components" top-nav item is not active within the Optimize section
The version selector shows main versions, instead of Optimize versions, in the Optimize section
The "this is unreleased documentation, see the latest version" warning does not appear in the Optimize section. (This one will likely take care of itself when I get to the stage of adding more Optimize versions)
The footer links to the next/previous documents are empty at the beginning/end of the Optimize section, and for the components surrounding Optimize the links skip over the Optimize section:

These items are all in scope of #1116, the parent issue, but I've elected to exclude them from this PR. I think they're all important issues for us to resolve, but I don't think they are required to move docs iteratively into the Optimize section. If you think I'm incorrect, and they are important to include in this PR, let me know!

Proof that it includes all latest Optimize updates

Note the last updated timestamp in the docs/components/optimize folder:

These timestamps are all older than the timestamp for the first commit in which I moved the what-is-optimize doc:

Implementation notes

The markdown links take advantage of the MDX plugin added in feat: MDX plugin to interpret link target URLs based on source file directory #1170, for a better experience linking across docs plugin instances.

Other notes

Note to future us: docusaurus has an item on their roadmap to enable separate docs plugins to talk to each other, at which time we might be able to undo this cross-linking experience in favor of something built into docusaurus 🙌

pepopowitz · 2022-08-16T16:18:58Z

docusaurus.config.js

+        id: "optimize",
+        path: "optimize",
+        routeBasePath: "optimize",
+        // sidebarPath: require.resolve("./optimize_sidebars.js"),


I'll remove this, it looks like it assumes this same path anyway.

pepopowitz · 2022-08-16T16:45:06Z

optimize/what-is-optimize.md

+- Automate
+- Improve
+
+A user can design process flows through our [Modeler](/docs/next/components/modeler/about-modeler/). In a production scenario, you can deploy through Desktop Modeler, Web Modeler, or programmatically. A user can use [Tasklist](/docs/next/components/tasklist/introduction-to-tasklist/) to review and complete tasks, and [Operate](/docs/next/components/operate/operate-introduction) to view and analyze process instances.


👋 👀

FYI I'm going to add an issue for the outcome of this very long note, but I also want to get feedback from people @christinaausley @akeller @korthout in case you think I'm wasting my time and being overly dramatic.

This is ....kind of sucky. These links all had to change from the originals. e.g. [Operate](/components/operate/operate-introduction.md) changed to [Operate](/docs/next/components/operate/operate-introduction)

Why?

This is because the links cross from one docs plugin to the other (that's how we implement multi-versioning in docusaurus -- two docs plugins, one for each set of versions).

Previously we were able to specify the doc ID and path via source....and docusaurus would magically find the doc you were linking to. We didn't need to know the URL, and we didn't have to specify a version because it used the same version you were browsing.

But now that they're cross-plugin, we have to specify the full URL of the target doc. This includes the version....which to some degree makes sense, because d-rex doesn't know that Optimize v3.8.0 is associated with C8 v8.0.

Why it's awful

Where it especially stinks though, is in the "next" and "current" docs. In the "next" docs, we'll want Optimize to link to C8 "next", and C8 to link to Optimize "next". When we cut versions 3.9.0/8.1 from that, we'll have to go through and replace every markdown link in those versions to remove the "/next" from the path. And then we'll have to go through the current 3.8.0/8.0 docs, and replace all those markdown links to add "/3.8.0" or "8.0".

This feels like a lot of friction. I didn't catch this when building the POCs. It'll be a pain for people writing docs because they can't just copy/paste their changes from the next version into current (or vice versa). It'll be a pain for reviewers because we'll overlook it all the time. It'll be a pain when we cut new versions.

There is also friction caused by sidebars needing to be expanded to include full URLs when crossing docs plugins. But I'm comfortable over-looking that friction because we don't modify the sidebars files very often.

Introducing friction on every markdown link, though, seems like it'll be extremely un-fun.

What I think we can do about it

So right now my theory is this: we could write an MDX plugin for these docs so that we can write something like this in the markdown:

Hello I like Camunda especially [the modeler]($docs$/components/modeler/about-modeler)

and the mdx plugin would see the $docs$ token, and replace it with the correctly mapped version path. e.g:

if it was found in a doc from optimize/next, it would replace it with /docs/next/

if it was found in a doc from optimize/3.7.0, it would replace it with /docs/1.3/

if it was found in a doc from optimize/3.8.0, /docs/ (at least right now....when 8.0 is current.)

and same to go backwards, from links found in docs from c8 into optimize.

A caveat

I haven't worked with MDX plugins before. I'm looking forward to the fun of writing one, but I don't really know what is or isn't possible in the context of a docusaurus site. So I guess we'll find out if my theory (or something similar) is anywhere feasible.

@RomanJRW wanted to pull you in here as well for feedback since you are the EM of Optimize.

@pepopowitz This friction aligns with what I expected from supporting this multi-version structured approach. I like the idea of the MDX plugin and would find it critical to support the Optimize and DX teams moving forward to reduce this friction.

This also assumes (or maybe implies is a better word here) that the versioning is tightly coupled.

Optimize 3.7.0 + CC 1.3

Optimize 3.8.0 + C8.0

Optimize 3.9.0 + C8.1

On the product side, I would want to understand if this is true. From a SaaS perspective, I think everything gets upgraded together when you hit the update button.

I tested with Zeebe 8.0.4 (Optimize 3.8.1) -> Zeebe 8.0.5 (Optimize 3.8.5). I had no option to update anything separately.

But what about for Self-Managed? Or can I upgrade/update Zeebe but not Optimize, or vice versa? This would be a question for the Optimize team. I would love for the documentation to mirror the recommended structure or coupling.

two bits of context I should have shared, from a conversation with @RomanJRW:

This list of optimize releases.

Optimize has decided to align their release schedule with that of C8. (I don't have this in writing anywhere, but I think that's what Josh told me)

Those two facts, combined with the fact that we only have "Optimize" docs starting in the platform version 1.3 docs, lead me to believe that the versioning is tightly coupled, with the specific versions you listed, and will be in the future.

@pepopowitz As part of the summerhackdays 2022, I recently created some MDX pages for Docusaurus that embed 2 custom build React components (LiveFeel, and Editor). This was rather simple TBH. I was surprised by the freedom we had in there.

I think that MDX plugins work similarly, but are embedded in a different way. As I understand it, the plugins are configured in docusaurus.config.js, instead of imported and embedded in each markdown file directly.

🔗 See the other comment in this file for an example of escaping this linking hell!

For posterity: it sounds like docusaurus has plans for v3 to enable different plugins to see each other's stuff. When that happens we might be able to undo this work 🙌

pepopowitz · 2022-08-16T16:47:30Z

optimize_sidebars.js

+    {
+      type: "link",
+      label: "Overview Components",
+      href: "/docs/next/components",
+    },


This is a foreseen down-side to the multi-version docs -- having to rewrite the sidebars files, and duplicate them, due to the two plugins not knowing about each others' docs.

sidebars.js

pepopowitz

Adding more comments based on another PR I'm about to open, for an MDX plugin that allows us to use tokens to represent paths that will be expanded based on the directory of the source file. In other words, much-easier-to-maintain cross-instance docs linking.

pepopowitz · 2022-08-17T18:59:39Z

docs/components/concepts/what-is-camunda-platform-8.md

@@ -63,7 +63,7 @@ With [Tasklist](../tasklist/introduction-to-tasklist.md), process owners can ach

 ### Optimize

-[Optimize](../optimize/what-is-optimize.md) leverages process execution data to continuously [provide actionable insights](../../guides/improve-processes-with-optimize.md). Optimize specializes in BPMN-based analysis and can show users exactly what their process model needs for successful execution.
+[Optimize]($optimize$/what-is-optimize) leverages process execution data to continuously [provide actionable insights](../../guides/improve-processes-with-optimize.md). Optimize specializes in BPMN-based analysis and can show users exactly what their process model needs for successful execution.


🔗 This uses the MDX plugin I wrote in (TODO: PR number) to have the site interpret which version of the optimize docs to send the user to, based on the location of the source file.

pepopowitz · 2022-08-17T19:00:41Z

docusaurus.config.js

+        id: "optimize",
+        path: "optimize",
+        routeBasePath: "optimize",
+        beforeDefaultRemarkPlugins: [versionedLinks],


🔗 This configures the optimize docs to use the MDX plugin that interprets link target URLs based on the source file directory.

pepopowitz · 2022-08-17T19:01:24Z

docusaurus.config.js

@@ -207,6 +219,7 @@ module.exports = {
          // Please change this to your repo.
          editUrl:
            "https://github.com/camunda/camunda-platform-docs/edit/main/",
+          beforeDefaultRemarkPlugins: [versionedLinks],


🔗 This configures the main docs to use the MDX plugin that interprets link target URLs based on the source file directory.

pepopowitz · 2022-08-17T19:02:03Z

optimize/what-is-optimize.md

+---
+
+:::note
+New to Optimize? Visit our introductory guide to [Optimize]($docs$/guides/improve-processes-with-optimize/) to get started.


🔗 This uses the MDX plugin from #1170 to have the site interpret which version of the main docs to send the user to, based on the location of the source file.

pepopowitz · 2022-08-17T19:03:09Z

optimize/what-is-optimize.md

+- Automate
+- Improve
+
+A user can design process flows through our [Modeler](/docs/next/components/modeler/about-modeler/). In a production scenario, you can deploy through Desktop Modeler, Web Modeler, or programmatically. A user can use [Tasklist](/docs/next/components/tasklist/introduction-to-tasklist/) to review and complete tasks, and [Operate](/docs/next/components/operate/operate-introduction) to view and analyze process instances.


🔗 See the other comment in this file for an example of escaping this linking hell!

…ere are no optimize versions yet

…t links at the optimize one

…ing between docs/optimize

…s quickly

pepopowitz

Adding some more comments for my recent changes

pepopowitz · 2022-08-25T19:44:42Z

docusaurus.config.js

+        path: "optimize",
+        routeBasePath: "optimize",
+        beforeDefaultRemarkPlugins: [versionedLinks],
+        sidebarPath: require.resolve("./optimize_sidebars.js"),


@akeller this is the line I had commented out that caused me to go down a rabbit hole yesterday.........docusaurus wasn't using my sidebars because I wasn't telling docusaurus to use them. 😅 😬

Funny how that works 😬

pepopowitz · 2022-08-25T19:47:16Z

hacks/generateOptimizeSidebars.md

+
+   - Make sure the results get formatted, as the script generates an object that does not match prettier's desired format.
+
+5. Replace/revert any Optimize links that exist within the optimize docs


As I move more and more docs over, this step might become enough of a pain that I figure out a way to make the script do doc-based links for already-moved docs.

You can always call in back up too if manually moving things gets the job done. I love the automated approach though.

pepopowitz · 2022-08-25T19:50:24Z

optimize_sidebars.js

+function docsComponentsLink(label, href) {
+  return {
+    type: "link",
+    label: label,
+    href: `/docs/next/${href}`,
+  };
+}


Long term vision:

I could have generated this file without this helper, but it would have resulted in /docs/next/ littered throughout it. This seems like it'd be not fun when we generate a new version of optimize -- we'd have to do a find/replace and include all those changes in the version PR.

Extracting the prefix of the paths to this one spot means we can just replace it in this one spot when we cut a new version.

It might be YAGNI, but it made sense to me.

pepopowitz · 2022-08-25T19:51:09Z

optimize_sidebars.js

+
+    {
+      Optimize: [
+        "what-is-optimize",


This is the only link in this sidebar file that is doc-based instead of URL based (because it's the only doc moved over in this PR).

pepopowitz · 2022-08-29T20:06:25Z

Heads up that this is ready for final review.

Also cc @christinaausley for visibility.

akeller

Nothing obviously concerning popping up for me. It makes sense the changes are only in /next/.

pepopowitz commented Aug 16, 2022

View reviewed changes

pepopowitz mentioned this pull request Aug 16, 2022

Investigate ways to reduce friction in cross-plugin markdown links #1167

Closed

pepopowitz force-pushed the pepopowitz/1116-configure-optimize-docs branch from 0c50270 to 915c7f0 Compare August 17, 2022 18:56

pepopowitz changed the base branch from main to pepopowitz/1167-markdown-links August 17, 2022 18:57

pepopowitz commented Aug 17, 2022

View reviewed changes

pepopowitz mentioned this pull request Aug 17, 2022

feat: MDX plugin to interpret link target URLs based on source file directory #1170

Merged

akeller added component:docs Documentation improvements, including new or updated content dx Documentation infrastructure typically handled by the Camunda DX team labels Aug 18, 2022

Base automatically changed from pepopowitz/1167-markdown-links to main August 22, 2022 15:14

This was referenced Aug 23, 2022

chore: remove vNext and optimize docs from sitemap temporarily #1193

Merged

Configure multi-instance versioning #1116

Closed

pepopowitz added 10 commits August 25, 2022 12:11

chore: initialize config for optimize docs

590175d

feat: optimize docs section (Next version only)

13c4464

feat: copy what-is-optimize to new optimize section

4ebd441

feat: update sidebars according to moved doc

81eb4f7

feat: enable cross-plugin versioned linking

11be3bb

feat: update all links in what-is-optimize to use tokens

60e21b9

wip: map optimize/ to docs/next and docs/next to optimize, because th…

526aaa2

…ere are no optimize versions yet

feat: remove what-is-optimize from docs folder and point all docs/nex…

aa52179

…t links at the optimize one

feat: add optimize sidebars, so the sidebar looks the same when bounc…

8662ecc

…ing between docs/optimize

feat: add a script (and instructions) for generating optimize sidebar…

e5ba999

…s quickly

pepopowitz force-pushed the pepopowitz/1116-configure-optimize-docs branch from 54996b2 to e5ba999 Compare August 25, 2022 17:11

pepopowitz requested a review from akeller August 25, 2022 19:35

pepopowitz changed the title ~~(WIP) feat: give optimize docs the correct versions~~ feat: give optimize docs the correct versions Aug 25, 2022

pepopowitz marked this pull request as ready for review August 25, 2022 19:36

pepopowitz commented Aug 25, 2022

View reviewed changes

pepopowitz changed the title ~~feat: give optimize docs the correct versions~~ feat: set up optimize docs instance and move one doc over Aug 26, 2022

pepopowitz self-assigned this Aug 26, 2022

pepopowitz mentioned this pull request Aug 29, 2022

feat: move "next" optimize docs into new optimize instance (subset #1) #1204

Merged

4 tasks

akeller approved these changes Aug 30, 2022

View reviewed changes

pepopowitz merged commit f5bc440 into main Aug 31, 2022

pepopowitz deleted the pepopowitz/1116-configure-optimize-docs branch August 31, 2022 15:47

pepopowitz added the epic:optimize-versions label Sep 22, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: set up optimize docs instance and move one doc over #1166

feat: set up optimize docs instance and move one doc over #1166

pepopowitz commented Aug 16, 2022 •

edited

Loading

pepopowitz Aug 16, 2022

pepopowitz Aug 16, 2022 •

edited

Loading

akeller Aug 16, 2022

pepopowitz Aug 16, 2022

korthout Aug 17, 2022 •

edited

Loading

pepopowitz Aug 17, 2022

pepopowitz Aug 23, 2022

pepopowitz Aug 16, 2022

pepopowitz left a comment

pepopowitz Aug 17, 2022

pepopowitz Aug 17, 2022

pepopowitz Aug 17, 2022

pepopowitz Aug 17, 2022 •

edited

Loading

pepopowitz Aug 17, 2022

pepopowitz left a comment

pepopowitz Aug 25, 2022

akeller Aug 26, 2022

pepopowitz Aug 25, 2022

akeller Aug 26, 2022

pepopowitz Aug 25, 2022

pepopowitz Aug 25, 2022

pepopowitz commented Aug 29, 2022

akeller left a comment


		- Make sure the results get formatted, as the script generates an object that does not match prettier's desired format.

		5. Replace/revert any Optimize links that exist within the optimize docs

feat: set up optimize docs instance and move one doc over #1166

feat: set up optimize docs instance and move one doc over #1166

Conversation

pepopowitz commented Aug 16, 2022 • edited Loading

Scope

Out of scope of this PR

Proof that it includes all latest Optimize updates

Implementation notes

Other notes

Choose a reason for hiding this comment

pepopowitz Aug 16, 2022 • edited Loading

Choose a reason for hiding this comment

Why?

Why it's awful

What I think we can do about it

A caveat

Choose a reason for hiding this comment

Choose a reason for hiding this comment

korthout Aug 17, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pepopowitz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pepopowitz Aug 17, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pepopowitz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pepopowitz commented Aug 29, 2022

akeller left a comment

Choose a reason for hiding this comment

pepopowitz commented Aug 16, 2022 •

edited

Loading

pepopowitz Aug 16, 2022 •

edited

Loading

korthout Aug 17, 2022 •

edited

Loading

pepopowitz Aug 17, 2022 •

edited

Loading